﻿<html DIR="LTR" xmlns:tool="http://www.microsoft.com/tooltip" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
  <head>
    <META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=utf-8" />
    <META NAME="save" CONTENT="history" />
    <title>Setting the Connection Properties</title>
    
    <link rel="stylesheet" type="text/css" href="../local/Classic.css">
      
    </link>
    
    <script src="../local/script.js">
      
    </script><script src="../local/script_main.js">&amp;nbsp;</script>
  </head>
  <body>
    <!--Topic built:03/05/2009 21:01:45-->

    
    
    
    
    
    
    
    
    
    <div id="header">
      <table width="100%" id="topTable"><tr>
          <td align="left">
            <span id="headerBold">Setting the Connection Properties</span>
          </td>
          <td align="right">
            
          </td>
        </tr></table>
      
      
      
    </div>
    <div id="mainSection">
      
        
        
		<font color="DarkGray"> </font> <p /> <p />
	
        <div id="introductionSection" class="section">
    <p>The connection string properties can be specified in various ways:</p>
    <ul><li>
        As name=value properties in the connection URL when you connect by using the <b>DriverManager</b> class. <br />
      </li><li>
        As name=value properties in the <i>Properties</i> parameter of the <b>Connect</b> method in the <b>DriverManager</b> class. <br />
      </li><li>
        As values in the appropriate setter method of the data source of the driver. For example: <br />
        <div class="sampleCode"><span codeLanguage="other"><pre>
          <b>datasource.setServerName(value)</b>
<b>datasource.setDatabaseName(value)</b></pre></span></div>
      </li></ul>
    <p>Property names are case-insensitive, and duplicate property names are resolved in the following order:</p>
    <ol><li>
        API arguments (such as user and password)<br />
      </li><li>
        Property collection<br />
      </li><li>
        Last instance in the connection string<br />
      </li></ol>
    <p>In addition, unknown values are allowed for the property names, and their values are not validated by the JDBC driver for case sensitivity.</p>
    <p>Synonyms are allowed and are resolved in order, just as are duplicate property names.</p>
    <p>The following table lists all the currently available connection string properties for the JDBC driver.</p>
    <table width="100%" cellspacing="0" cellpadding="0" border="1" style="background-color: #CCCCCC;"><tr>
          <th>
            Property
          </th>
          <th>
            Type
          </th>
          <th>
            Default
          </th>
          <th>
            Description
          </th>
        </tr><tr>
        <td>
          <p>applicationName</p>
        </td>
        <td>
          <p>String </p>
          <p>[&lt;=128 char]</p>
        </td>
        <td>
          <p>null</p>
        </td>
        <td>
          <p>The application name, or "Microsoft SQL Server JDBC Driver" if no name is provided. Used to identify the specific application in various SQL Server profiling and logging tools.</p>
        </td>
      </tr><tr>
        <td>
          <p>databaseName, database</p>
        </td>
        <td>
          <p>String</p>
          <p>[&lt;=128 char]</p>
        </td>
        <td>
          <p>null</p>
        </td>
        <td>
          <p>The name of the database to connect to. If not stated, a connection is made to the default database.</p>
        </td>
      </tr><tr>
        <td>
          <p>disableStatementPooling</p>
        </td>
        <td>
          <p>boolean</p>
          <p>["true"|"false"]</p>
        </td>
        <td>
          <p>true</p>
        </td>
        <td>
          <p>Only the value "true" is currently supported. If set to "false", an exception will occur.</p>
        </td>
      </tr><tr>
        <td>
          <p>encrypt</p>
        </td>
        <td>
          <p>boolean</p>
          <p>["true"|"false"]</p>
        </td>
        <td>
          <p>false</p>
        </td>
        <td>
          <p>Set to "true" to specify that the SQL Server uses Secure Sockets Layer (SSL) encryption for all the data sent between the client and the server if the server has a certificate installed. The default value is false.</p>
        </td>
      </tr><tr>
        <td>
          <p>failoverPartner</p>
        </td>
        <td>
          <p>String</p>
        </td>
        <td>
          <p>null</p>
        </td>
        <td>
          <p>The name of the failover server used in a database mirroring configuration. This property is used for an initial connection failure to the principal server; after you make the initial connection, this property is ignored. Must be used in conjunction with databaseName property.</p>
          <div style="margin: .5em 1.5em .5em 1.5em"><b>Note: </b>
            The driver does not support specifying the server instance port number for the failover partner instance as part of the failoverPartner property in the connection string. However, specifying the serverName, instanceName and portNumber properties of the principal server instance and failoverPartner property of the failover partner instance in the same connection string is supported.<p />
          </div>
        </td>
      </tr><tr>
        <td>
          <p>hostNameInCertificate</p>
        </td>
        <td>
          <p>String </p>
        </td>
        <td>
          <p>null</p>
        </td>
        <td>
          <p>The host name to be used in validating the SQL Server SSL certificate.</p>
          <p>If the hostNameInCertificate property is unspecified or set to null, the Microsoft SQL Server JDBC Driver will use the <b>serverName</b> property value on the connection URL as the host name to validate the SQL Server SSL certificate. </p>
          <div style="margin: .5em 1.5em .5em 1.5em"><b>Note: </b>
            This property is used in combination with the <b>encrypt</b> property and the <b>trustServerCertificate</b> property. This property affects the certificate validation, if and only if the <b>encrypt</b> property is set to "true" and the <b>trustServerCertificate</b> is set to "false".<p />
          </div>
        </td>
      </tr><tr>
        <td>
          <p>instanceName</p>
        </td>
        <td>
          <p>String</p>
          <p>[&lt;=128 char]</p>
        </td>
        <td>
          <p>null</p>
        </td>
        <td>
          <p>The SQL Server instance name to connect to. When it is not specified, a connection is made to the default instance. For the case where both the instanceName and port are specified, see the notes for port.</p>
        </td>
      </tr><tr>
        <td>
          <p>integratedSecurity</p>
        </td>
        <td>
          <p>boolean</p>
          <p>["true"|"false"]</p>
        </td>
        <td>
          <p>false</p>
        </td>
        <td>
          <p>Set to "true" to indicate that Windows credentials will be used by SQL Server to authenticate the user of the application. If "true," the JDBC driver searches the local computer credential cache for credentials that have already been provided at the computer or network logon. If "false," the username and password must be supplied.</p>
          <div style="margin: .5em 1.5em .5em 1.5em"><b>Note: </b>
            This connection property is only supported on Microsoft Windows operating systems.<p />
          </div>
        </td>
      </tr><tr>
        <td>
          <p>lastUpdateCount</p>
        </td>
        <td>
          <p>boolean</p>
          <p>["true"|"false"]</p>
        </td>
        <td>
          <p>true</p>
        </td>
        <td>
          <p>A "true" value only returns the last update count from an SQL statement passed to the server, and it can be used on single SELECT, INSERT, or DELETE statements to ignore additional update counts caused by server triggers. Setting this property to "false" causes all update counts to be returned, including those returned by server triggers.</p>
          <div style="margin: .5em 1.5em .5em 1.5em"><b>Note: </b>
            This property only applies when it is used with the <a href="10ae662a-ce3c-4b24-875c-5c2df319d93b.htm">executeUpdate</a> methods. All other <b>execute</b> methods return all results and update counts. <p />
            This property only affects update counts returned by server triggers. It does not affect result sets or errors that result as part of trigger execution.<p />
          </div>
        </td>
      </tr><tr>
        <td>
          <p>lockTimeout</p>
        </td>
        <td>
          <p>int</p>
        </td>
        <td>
          <p>-1</p>
        </td>
        <td>
          <p>The number of milliseconds to wait before the database reports a lock time-out. The default behavior is to wait indefinitely. If it is specified, this value is the default for all statements on the connection. Note that<code> Statement.setQueryTimeout() </code>can be used to set the time-out for specific statements. The value can be 0, which specifies no wait.</p>
        </td>
      </tr><tr>
        <td>
          <p>loginTimeout</p>
        </td>
        <td>
          <p>int [0..65535]</p>
        </td>
        <td>
          <p>15</p>
        </td>
        <td>
          <p>The number of seconds the driver should wait before timing out a failed connection. A zero value indicates that the timeout is the default system timeout, which is specified as 15 seconds by default. A non-zero value is the number of seconds the driver should wait before timing out a failed connection.</p>
        </td>
      </tr><tr>
        <td>
          <p>packetSize</p>
        </td>
        <td>
          <p>int [-1| 0 | 512..32767]</p>
        </td>
        <td>
          <p>8000</p>
        </td>
        <td>
          <p>The network packet size used to communicate with SQL Server, specified in bytes. A value of -1 indicates using the server default packet size. A value of 0 indicates using the maximum value, which is 32767. If this property is set to a value outside the acceptable range, an exception will occur.</p>
          <div style="margin: .5em 1.5em .5em 1.5em"><b>Important: </b>
            We do not recommend using the packetSize property when the encryption is enabled (encrypt=true). Otherwise, the driver might raise a connection error. For more information, see the <a href="5d490edc-a223-4870-a838-784952497e5f.htm">setPacketSize</a> method of the <a href="097434fd-2b74-411c-a5ed-eba04481dde5.htm">SQLServerDataSource</a> class.<p />
          </div>
        </td>
      </tr><tr>
        <td>
          <p>password</p>
        </td>
        <td>
          <p>String </p>
          <p>[&lt;=128 char]</p>
        </td>
        <td>
          <p>null</p>
        </td>
        <td>
          <p>The database password.</p>
        </td>
      </tr><tr>
        <td>
          <p>portNumber, port</p>
        </td>
        <td>
          <p>int [0..65535]</p>
        </td>
        <td>
          <p>1433</p>
        </td>
        <td>
          <p>The port where SQL Server is listening. If the port number is specified in the connection string, no request to sqlbrowser is made. When the port and instanceName are both specified, the connection is made to the specified port. However, the instanceName is validated and an error is thrown if it does not match the port.</p>
          <div style="margin: .5em 1.5em .5em 1.5em"><b>Important: </b>
            We recommend that the port number always be specified, as this is more secure than using sqlbrowser.<p />
          </div>
        </td>
      </tr><tr>
        <td>
          <p>responseBuffering</p>
        </td>
        <td>
          <p>String</p>
          <p>["full"|"adaptive"]</p>
        </td>
        <td>
          <p>adaptive</p>
        </td>
        <td>
          <p>If this property is set to "adaptive", the minimum possible data is buffered when necessary. The default mode is "adaptive" for the Microsoft SQL Server JDBC Driver version 2.0 or later.</p>
          <p>When this property is set to "full", the entire result set is read from the server when a statement is executed. The default mode was "full" for the Microsoft SQL Server 2005 JDBC Driver version 1.2 and provides a backward compatibility with the Microsoft SQL Server 2005 JDBC Driver versions 1.0, 1.1, and 1.2.</p>
          <div style="margin: .5em 1.5em .5em 1.5em"><b>Note: </b>
            <p />
            After upgrading the JDBC driver from version 1.2 to 2.0, the default buffering behavior will be "adaptive." If your application has never set the "responseBuffering" property and you want to keep the version 1.2 default behavior in your application, you must set the responseBufferring propery to "full" either in the connection properties or by using the <a href="9f489835-6cda-4c8c-b139-079639a169cf.htm">setResponseBuffering</a> method of the <a href="ec24963c-8b51-4838-91e9-1fbfa2347451.htm">SQLServerStatement</a> object.<p />
          </div>
        </td>
      </tr><tr>
        <td>
          <p>selectMethod</p>
        </td>
        <td>
          <p>String</p>
          <p>["direct"|"cursor"]</p>
        </td>
        <td>
          <p>direct</p>
        </td>
        <td>
          <p>If this property is set to "cursor," a database cursor is created for each query created on the connection for TYPE_FORWARD_ONLY and CONCUR_READ_ONLY cursors. This property is typically required only if the application generates very large result sets that cannot be fully contained in client memory. When this property is set to "cursor," only a limited number of result set rows are retained in client memory. The default behavior is that all result set rows are retained in client memory. This behavior provides the fastest performance when the application is processing all rows.</p>
        </td>
      </tr><tr>
        <td>
          <p>sendStringParametersAsUnicode</p>
        </td>
        <td>
          <p>boolean</p>
          <p>["true"|"false"]</p>
        </td>
        <td>
          <p>true</p>
        </td>
        <td>
          <p>If the sendStringParametersAsUnicode property is set to "true", String parameters are sent to the server in Unicode format. </p>
          <p>If the sendStringParametersAsUnicode property is set to “false", String parameters are sent to the server in non-Unicode format such as ASCII/MBCS instead of Unicode. </p>
          <p>The default value for the sendStringParametersAsUnicode property is "true".</p>
          <p> </p>
          <div style="margin: .5em 1.5em .5em 1.5em"><b>Note: </b>
            In the JDBC Driver version 2.0, the sendStringParametersAsUnicode property is only checked when sending a parameter value with <b>CHAR</b>, <b>VARCHAR</b>, or <b>LONGVARCHAR</b> JDBC types. The new JDBC 4.0 national character methods, such as the <b>setNString</b>, <b>setNCharacterStream</b>, and <b>setNClob</b> methods of <a href="a8481c06-fbba-432b-8c69-4f4619c20ad4.htm">SQLServerPreparedStatement</a> and <a href="30710a63-c05d-47d9-9cf9-c087a1c76373.htm">SQLServerCallableStatement</a> classes, always send their parameter values to the server in Unicode regardless of the setting of this property. <p />
            For optimal performance with the <b>CHAR</b>, <b>VARCHAR</b>, and <b>LONGVARCHAR</b> JDBC data types, an application using version 2.0 of the JDBC driver should set the sendStringParametersAsUnicode property to "false" and use the <b>setString</b>, <b>setCharacterStream</b>, and <b>setClob</b> non-national character methods of the <a href="a8481c06-fbba-432b-8c69-4f4619c20ad4.htm">SQLServerPreparedStatement</a> and <a href="30710a63-c05d-47d9-9cf9-c087a1c76373.htm">SQLServerCallableStatement</a> classes. <p />
            When the application sets the <b>sendStringParametersAsUnicode</b> property to "false" and uses a non-national character method to access Unicode data types on the server side (such as <b>nchar</b>, <b>nvarchar</b> and <b>ntext</b>), some data might be lost if the database collation does not support the characters in the String parameters passed by the non-national character method.<p />
            Note that an application should use the <b>setNString</b>, <b>setNCharacterStream</b>, and <b>setNClob</b> national character methods of the <a href="a8481c06-fbba-432b-8c69-4f4619c20ad4.htm">SQLServerPreparedStatement</a> and <a href="30710a63-c05d-47d9-9cf9-c087a1c76373.htm">SQLServerCallableStatement</a> classes for the <b>NCHAR</b>, <b>NVARCHAR</b>, and <b>LONGNVARCHAR</b> JDBC data types.<p />
          </div>
        </td>
      </tr><tr>
        <td>
          <p>serverName, server</p>
        </td>
        <td>
          <p>String</p>
        </td>
        <td>
          <p>null</p>
        </td>
        <td>
          <p>The computer running SQL Server.</p>
        </td>
      </tr><tr>
        <td>
          <p>userName, user</p>
        </td>
        <td>
          <p>String </p>
          <p>[&lt;=128 char]</p>
        </td>
        <td>
          <p>null</p>
        </td>
        <td>
          <p>The database user.</p>
        </td>
      </tr><tr>
        <td>
          <p>trustServerCertificate</p>
        </td>
        <td>
          <p>boolean</p>
          <p>["true"|"false"]</p>
        </td>
        <td>
          <p>false</p>
        </td>
        <td>
          <p>Set to "true" to specify that the Microsoft SQL Server JDBC Driver will not validate the SQL Server SSL certificate.</p>
          <p>If "true", the SQL Server SSL certificate is automatically trusted when the communication layer is encrypted using SSL.</p>
          <p>If "false", the Microsoft SQL Server JDBC Driver will validate the server SSL certificate. If the server certificate validation fails, the driver will raise an error and terminate the connection. The default value is "false".</p>
          <div style="margin: .5em 1.5em .5em 1.5em"><b>Note: </b>
            This property is used in combination with the <b>encrypt</b> property. This property only affects the server SSL certificate validation if and only if the <b>encrypt</b> property is set to "true".<p />
          </div>
        </td>
      </tr><tr>
        <td>
          <p>trustStore</p>
        </td>
        <td>
          <p>String </p>
        </td>
        <td>
          <p>null</p>
        </td>
        <td>
          <p>The path (including filename) to the certificate trustStore file. The trustStore file contains the list of certificates that the client trusts. </p>
          <p>When this property is unspecified or set to null, the driver will rely on the trust manager factory's look up rules to determine which certificate store to use. </p>
          <p>The default SunX509 TrustManagerFactory tries to locate the trusted material in the following search order:</p>
          <ul><li>
              A file specified by the "javax.net.ssl.trustStore" Java Virtual Machine (JVM) system property. <br />
            </li><li>
              "&lt;java-home&gt;/lib/security/jssecacerts" file. <br />
            </li><li>
              "&lt;java-home&gt;/lib/security/cacerts" file.<br />
            </li></ul>
          <p>For more information, see the SUNX509 TrustManager Interface documentation on the Sun Microsystems Web site.</p>
          <div style="margin: .5em 1.5em .5em 1.5em"><b>Note: </b>
            This property only affects the certificate trustStore lookup, if and only if the <b>encrypt</b> property is set to "true" and the <b>trustServerCertificate</b> property is set to "false".<p />
          </div>
        </td>
      </tr><tr>
        <td>
          <p>trustStorePassword</p>
        </td>
        <td>
          <p>String </p>
        </td>
        <td>
          <p>null</p>
        </td>
        <td>
          <p>The password used to check the integrity of the trustStore data. </p>
          <p>If the trustStore property is set but the trustStorePassword property is not set, the integrity of the trustStore is not checked.</p>
          <p>When both trustStore and trustStorePassword properties are unspecified, the driver will use the JVM system properties, "javax.net.ssl.trustStore" and "javax.net.ssl.trustStorePassword". If the "javax.net.ssl.trustStorePassword" system property is not specified, the integrity of the trustStore is not checked. </p>
          <p>If the trustStore property is not set but the trustStorePassword property is set, the JDBC driver will use the file specified by the "javax.net.ssl.trustStore" as a trust store and the integrity of the trust store is checked by using the specified trustStorePassword. This might be needed when the client application does not want to store the password in the JVM system property.</p>
          <div style="margin: .5em 1.5em .5em 1.5em"><b>Note: </b>
            The trustStorePassword property only affects the certificate trustStore lookup, if and only if the <b>encrypt</b> property is set to "true" and the <b>trustServerCertificate</b> property is set to "false".<p />
          </div>
        </td>
      </tr><tr>
        <td>
          <p>workstationID</p>
        </td>
        <td>
          <p>String </p>
          <p>[&lt;=128 char]</p>
        </td>
        <td>
          <p>&lt;empty string&gt;</p>
        </td>
        <td>
          <p>The workstation ID. Used to identify the specific workstation in various SQL Server profiling and logging tools. If none is specified, the &lt;empty string&gt; is used.</p>
        </td>
      </tr><tr>
        <td>
          <p>xopenStates</p>
        </td>
        <td>
          <p>boolean</p>
          <p>["true"|"false"]</p>
        </td>
        <td>
          <p>false</p>
        </td>
        <td>
          <p>Set to "true" to specify that the driver returns XOPEN-compliant state codes in exceptions. The default is to return SQL 99 state codes.</p>
        </td>
      </tr></table>
  </div><span id="seeAlsoSpan"><h1 class="heading">See Also</h1></span><div id="seeAlsoSection" class="section" name="collapseableSection"><a href="94bcfbe3-f00e-4774-bda8-bb7577518fec.htm">Connecting to SQL Server with the JDBC Driver</a><br /><br /></div><!--[if gte IE 5]>
			<tool:tip element="seeAlsoToolTip" avoidmouse="false"/><tool:tip element="languageFilterToolTip" avoidmouse="false"/><tool:tip element="roleInfoSpan" avoidmouse="false"/>
		<![endif]-->
      <div id="footer" class="section">
        
		<hr />
		
		<span id="fb" class="feedbackcss">
			
			
		</span>
		
		<a href="9bad553b-9e70-4696-8499-2e35f772a1e0.htm">
			
			© 2009 Microsoft Corporation. All rights reserved.
		</a>
 	
	
      </div>
    </div>
  </body>
</html>